home *** CD-ROM | disk | FTP | other *** search
/ Netware Super Library / Netware Super Library.iso / acss_com / pcbridge / src.doc < prev    next >
Text File  |  1991-03-26  |  10KB  |  205 lines
  1.  
  2.                         PCbridge source code description
  3.                                 Vance Morrison
  4.  
  5.  
  6.     PCbridge is distributed with source for essentially one reason, I would 
  7. like to involve many people in the design and debugging of PCbridge, and for 
  8. them to do this, they need the source.   Since I will not be the only one
  9. fixing bugs and adding enhancements, PCbridge will continue to develop as long
  10. as there are people who think it is a worthwhile program to support.  As
  11. creator of PCbridge, however I request/demand the following
  12.  
  13.  
  14.         1) Please let me know about any bug fixes so that I can incorporate
  15.            them into the 'official' release.
  16.  
  17.         2) You may make local enhancements to PCbridge and use them LOCALLY
  18.            (that is within the same organization) but you may NOT distribute
  19.            this code.  
  20.  
  21.     The reason for the second demand (it is in the copywrite) is very simple,
  22. I don't want PCbridge to fragment into many versions.   That is my ONLY 
  23. concern.  Thus just tell me what you want to do, and I will give you
  24. an copy of the working source code, and you can be sure that the part that
  25. you are working on is not being worked on by anyone else, and when you are
  26. done it will be ready to integrate into the official release.   I do
  27. reserve the right NOT to integrate features that I regard as counterproductive
  28. and code that simply is too poorly written or buggy to risk, but I do not
  29. see myself excercising that option.  
  30.  
  31.     All of these conditions are simply to insure that PCbridge has a long
  32. and productive life.   I have no monetary interest in PCbridge.  
  33.  
  34. ============================================================================
  35. DESIGN CRITERIA
  36.  
  37.     PCbridge had to be designed to squeeze all the power it could out
  38. of an 8088 CPU.  As such I had to make some rather drastic measures.
  39. These include
  40.  
  41.         1) Programming the main packet routing loop in assembler
  42.         2) NO procedure call in the main packet routing loop
  43.  
  44.     Since assembler have very good macro expansion capabilities, the
  45. second decision is relatively painless.  Simply use macros instead
  46. of procedure calls.   This can make the code large, but memory has
  47. not been a problem yet.  
  48.  
  49.     Once we are out of the main packet loop, these optimizations are
  50. not really necessary anymore.  Thus if/when SNMP support is added
  51. to PCbridge, it will be done in C, since all of this code is only 
  52. executed when SNMP operations are being done.
  53.  
  54. ===========================================================================
  55.  
  56. CONVENTIONS
  57.  
  58.     Despite the use use of assembler, I have tried to make the code 
  59. as modular as possible, and to adopt conventions that I have found quite
  60. useful in preventing common assembly code errors.   Some of these 
  61. conventions are
  62.  
  63.     1) function prefixing - Macros are groups into modules that provide
  64.           a set of related services.  All function in this group are 
  65.           prefixed by the same short string.  This improves readability
  66.           and prevents name conflicts
  67.  
  68.     2) Naming input, output and constant registers - The most common
  69.           error in assembly code is calling a macro that changes registers
  70.           that you believed where held constant.  To prevent this type
  71.           of error Macro names have the following form
  72.  
  73.                 <NAME>_in_<REG LIST>_out_<REG_LIST>_const_<REG_LIST>
  74.  
  75.           For example
  76.  
  77.               WD_IF_COPY_in_CX_SI_DI_ES_out_SI_DI_const_BX_BP_ES name
  78.  
  79.           It is quite clear from the name that this macro has its parameters
  80.           passed in CX,SI,DI,ES, it returns values in SI,DI and it holds
  81.           the registers BX,BP,ES constant.  While this may seem long-winded
  82.           (it is) it is VERY useful and has prevented many bugs and I
  83.           will DEMAND that any new assembly code follow these conventions.
  84.  
  85.           Note that since the CS,DS,SS registers are NEVER changed, you
  86.           may assume that EVERY macro preserves these registers. 
  87.  
  88.     3) file naming - There are two type of files in the source code at
  89.          present, INC files and ASM files.  INC files contain ONLY macro
  90.          definitions and admit NO code and are meant to be included in
  91.          ASM files.  INC file are thus the 'meat' of the code.  The ASM
  92.          files contain NO macro definitions, but do instantiate the macros
  93.          to generate the actual code.   At present there is only one
  94.          ASM file (BRIDGE.ASM).
  95.          
  96. ===========================================================================
  97.  
  98. The IF interface:
  99.  
  100. The IF interface is a device-independant view of a network card.  Thus
  101. new hardware can be supported simply by writing code to implement an
  102. IF interface for the new hardware.
  103.  
  104.         IF.INC          Supplies a standard interface for all card specific
  105.                         code and dispatches the proper code when generic
  106.                         routines are called.
  107.  
  108. ===========================================================================
  109.  
  110. IF interfaces for 3COM 3c507 Ethernet:
  111.  
  112. The following file implement a IF interface for 3COM 3c507 card
  113.  
  114.         3C507.INC       IF interface specific to the 3c507.INC file
  115.  
  116. ===========================================================================
  117.  
  118. IF interfaces for WD Ethernet and Starlan code:
  119.  
  120. The following files implement a IF interface for Western digital cards
  121.  
  122.         WD8003E.INC     IF interface specific to the WD8003E, WD8003EBT
  123.                         and WD8013EBT cards.  It also works with WD8003S
  124.                         and WD8003SH starlan cards, but the buffering
  125.                         is not optimized for these slower cards.
  126.  
  127.         WD.INC          Constant declarations needed by the above two
  128.                         modules to manipulate the WD8003 card.
  129.  
  130. ==========================================================================
  131.  
  132. IF interface for the packet driver
  133.  
  134.         PACKET.INC      Implements an IF intererface for FTP software's
  135.                         packet driver specification.   Since many packet
  136.                         drivers have been written for may cards, this
  137.                         module immediately provides support for all these
  138.                         cards.  Unforunately, the packet driver specification
  139.                         is not highly optimized for throughput, thus this
  140.                         interface is usually 1/3 the speed of a 'native'
  141.                         IF interface.  
  142.  
  143. ==========================================================================
  144.  
  145. IF interface for a serial COM port
  146.  
  147.         I8250.INC       Implements code for getting and putting single
  148.                         characters on and off a 8250 serial chip.  It
  149.                         also has support for the 166550AF chip with FIFOs.
  150.                         This module is the only one that has to deal with
  151.                         the vugarities of setting interupts and dealing
  152.                         directly with the serial chip.
  153.  
  154.         SLIP.INC        The stream of input characters from the I8250
  155.                         interface and packatizes them according to the
  156.                         SLIP protocol.  Also adds packet markers to 
  157.                         outgoing packets producing a outgoing character
  158.                         stream that the I8250 module transmits.
  159.  
  160.         QIF.INC         Impelents the 'other half' of the packet queuing.
  161.                         It is this code that queues up incomming and
  162.                         outgoing packets.  It looks like a IF interface
  163.                         to higher levels.
  164.  
  165. ==========================================================================
  166.  
  167. The Bridge Code:
  168.  
  169.        BRIDGE.INC       This file implements the actually packet bridging
  170.                         algorithm.  In addition, it also acts like a IF
  171.                         interface.  The idea is that any packets that are
  172.                         not addressed to the bridge are inspected and 
  173.                         bridged if necessary, however if a packet is sent
  174.                         directly to the address of the bridge this packet
  175.                         is sent to the higher level (via an IF interface)
  176.                         for processing.  This allows the possibility for
  177.                         Bridge-routing or network control (SNMP).  
  178.  
  179.       BRIDGE.ASM        The 'main program' for the bridge.  This file
  180.                         is only one you should need to change to reconfigure
  181.                         the bridge (see compile.doc). 
  182.  
  183. ===========================================================================
  184.  
  185. Support routines
  186.  
  187.     In addition to the major functional blocks, there are some modules that
  188. provide rather generic services that are used by the other functional blocks.
  189. These modules include
  190.  
  191.         DEBUG.INC       Provides simple routines that print to screen routines.
  192.                         They should not be in production code (use log routines)
  193.                         These routines violate convention in that they
  194.                         preserve ALL registers but do not have a CONST
  195.                         part in their name.
  196.  
  197.         BUFFER.INC      Provides simple buffer allocation routines used in
  198.                         output (and possibly input) queuing.  Used in
  199.                         QIF.INC ATALK.INC and WD8003.INC
  200.  
  201.         QUEUE.INC       Provides simple queuing routines used for packet
  202.                         queues.  Used in ATALK.INC and WD8003.INC
  203.  
  204. ==========================================================================
  205.